general_staff_wargaming_systemfandomcom-20200214-history
The General Staff Black Powder Map Editor
Map Editor Overview The General Staff Black Powder Map Editor (hence referred to as the Map Editor) allows you to create new battlefield maps for use with the General Staff Black Powder Wargaming System. In many ways the Map Editor is a traditional multi-layered paint program with similar functionality as popular paint programs like PhotoShop, In the above schematic image we see that there are four possible layers in a General Staff battlefield map: Place Names & Victory Points '''(optional), '''Terrain, Elevation and Background Image (optional). After a map is created and saved in the Map Editor it can be loaded into the General Staff Black Powder Scenario Editor and used to create new or historical battles that are then played in the General Staff Black Powder Wargame. '''It is important to remember that how your map looks when it is saved (with terrain and elevation opacity settings) is how it will appear in the game.' You will be drawing '''Terrain Objects' (such as forests, lakes, roads, etc.) on your map. These objects can be individually deleted or merged with similar terrain objects. You also have the ability to import digital scans of historical battlefield maps, add terrain and elevation data, and save the map for use with the General Staff Wargaming System. Aim This section describes what you're aiming to achieve by drawing a map. Very broadly speaking, there are four products of your input. 1) A jpg picture which is a visual representation of terrain for the user. They know where a road is because there's a line in the picture. 2) A list of Places with optional Victory Points. These have meaning to both the user visually and they are how the app will work out you captured a strategically important location. These are considered separately from all other terrain you draw because they don't just become part of a background jpg. 3) A matrix ( two dimensional array ) of terrain types. Each pixel has a value for what terrain is there. This is used by the computer to tell it where a road is. The order things are added matters and last wins. Hence a road over a river defines a crossing place where your infantry will not drown. 4) A matrix ( two dimensional array ) of elevation. Each pixel has a height in metres. This is how high your hill is and is if you like third dimension - the Z component. ( X and Y being the other 2 dimensions ). This is used by the computer to know height. It is due to the last three points that you cannot just grab any old map and meaningfully use that as the background. If you did then the computer would have no way of knowing what terrain is where. It'd be just a picture as far as the computer is concerned. In fact the picture is not used for any calculations by the apps. 'Digitizing Tablets & Pens' The Map Editor ''supports the use of digitizing tablets and pens as well as the standard two button + scroll button mouse. You don't absolutely need a stylus but you will want the scroll wheel functionality for advanced drawing. '''The Map Editor Screen' Upon running the Map Editor your screen will look like this: The screen is divided into two areas: the Tool Pane on the left hand side of the screen and the Drawing Canvas which takes up most of the screen. Above these two sections are a standard Menu Bar. '''The grid lines and the Compass Rose are optional and can be toggled on/off from the '''Layers menu. The Tool Pane Drawing tools, tool options and map information is entered in the Tool Pane area on the left portion of the screen. Clicking on the left or right arrows on either side of the tab title will scroll to the previous / next tab (see above image). The Map Options Tab The Map Options Tab is where you enter information about the map itself. There are three options: Map Name The Map Name is, obviously, the name of the map. A descriptive name, like Sharpsburg, September 17, 1862 would be appropriate. Map Description Enter a descriptive text about the map. This information is saved with the map. Map DPI You can select the DPI (Dots Per Inch) resolution that the map will be saved at (either 96, 300, 600, 1200 or 2400). Remember: the greater the DPI the larger the file size! You may wish to save the map at higher DPI resolution if you intend to print out the map (very handy for board gamers) or if you have a high resolution monitor. The Drawing Options Tab These are the tools that you will be using to draw on the Drawing Canvas portion of the screen. When you choose to work with one of the Area or Line tools on the... Drawing Options Tab your map cursor will change to a pen: Note: '''You are drawing on the '''Terrain Layer. The Drawing Options Tab is divided into three sections: Area Drawing Tools Area Drawing Tools are tools for drawing filled in areas on the map like Forests, Lakes and Swamps. When you draw on the Drawing Canvas with an Area Drawing Tool your start and end points are automatically connected and the enclosed area is filled in with the selected terrain type. If you are using a mouse to draw the start point is where you click down with the left mouse button. Hold the left mouse button down until you have arrived at your end point and then release the left mouse button. The start and end points are automatically connected. If you are using a digitizing table and pen press down on the tablet with the pen at the start point, continue drawing with the pen until you reach the end point and then lift the pen off of the drawing tablet. The start and end points are automatically connected. 'Setting Base Width' If you're using a stylus then the harder you press, the wider a line terrain will get. If you're instead using a mouse ( most users will probably only have a mouse ) the width is fixed to the value equivalent to 0.5 pressure. Pressure ranges from 0 to 1. You can set the base width for each line terrain. You need a mouse or a stylus which has a scroll wheel (yes, some do). Position the cursor over the desired tool option (for example, River) you should see a tooltip appear like the picture below. Then use the mouse scroll wheel to increase or decrease the values. "As drawn" is 0.5 pressure and what you will get with a mouse. Max is the maximum width you will get with 1 pressure or at the end of a river you use the widening option on. This will allow you to draw rivers that widen or decrease in width based solely on the amount you press down on the digital pen. Selecting a Drawing Tool You can either click an option or cycle through them using up / down arrows. Although these look rather like buttons ( for immediate familiarity ) they're not. When you select a drawing tool the background darkens and a rosette will appear to give a visual confirmation: 'Forest Drawing Tool' An example of using the Forest Drawing Tool. Note the quill pen indicates progress adding the trees as "children" of the forest. The process which adds the trees calculates how many to add based on area. It looks for a space to fit one by randomly picking a point and checking whether there's a tree there already. As trees are added there are less and less points "free" and finding a new space takes a bit longer. The size of the trees is reduced as you go but you will notice it can take quite some time for large complex forests. This mechanism of adding "children" is used in other area tools ( waves for lakes ) except there are less children and they will usually run much faster. The Lake Drawing Tool The Swamp Drawing Tool The Mud Drawing Tool The Field Drawing Tool The City Drawing Tool The Contour Drawing Tool ''' Use the Contour Drawing Tool to draw elevation contours (above). ''Important: this tool does not add elevation to the map. That is done either by importing Elevation Data or Drawing Elevation Data'' (see below) '''Line Drawing Tools Line drawing tools are different than Area Drawing Tools (see above) in that the start and end points of the line are not automatically connected. The Road Drawing Tool The River Drawing Tool The Fortification / Wall Drawing Tool The Boundary Drawing Tool The Bridge Drawing Tool The Ford Drawing Tool The Point Drawing Tools Point drawing tools are tools that you just click once on the map to label a geographic location. These can be either labels like 'Swamp' or 'East Woods' or Victory Point areas that help determine a simulation's victors. This tool is also used for placing buildings. The Placename / Victory Point Drawing Tool The Building Drawing Tool The Edit Terrain Tab Once you have added at least one terrain then you will see it appear in the list on the Edit Terrain Tab. You will have various options in the left pane for each terrain. In the right, you can right click area terrains and choose one of three options. Removing the children will remove the trees, redoing the children will remove and then re-fill with trees and setting the background transparent will remove the speckled fill. The latter is particularly useful if you already have a background map which includes imagery you wish to retain. This could be a forest or city on a map out a history book or scan that you're using as background. The Obtain Elevation Data Tab ( Preliminary write up ). This tab uses data from Google Maps. In order to use this (optional) functionality you will need to create a Google Maps Platform account. The relationship for this service is of course between you and Google. The details of this have been subject to recent change, but are explained: https://cloud.google.com/maps-platform/ Although you register a credit card, the service is effectively free for normal usage since you get $200 "credit" each month. If you want to create many maps using this service then use Google's pages to check usage. Current costing is $5 per 1,000 calls. A map's worth of data is 579 calls. You will be given a unique id which is necessary to call the service. Once you have registered and have this long string of characters and numbers, create a txt file ( notepad ) called googlekey in: %localappdata%/generalstaff The reason this is a manual process external to GeneralStaff is to ensure you understand this is not part of our code you will be using. Google's Elevation API is by far the most convenient source of real world elevation data but rather quirky. Presumably due to past abuses the service was sensitive to the high number of calls necessary for our purposes. Until recently it was taking two runs to obtain a full map's worth of data. If the download stops mid run, save your map and try again several hours later to obtain the rest. If you try immediately and the failure was because Google decided you were asking for too much data, it will always fail. On the plus side the recent change to force credit card registration seems to have allowed them to remove or reduce the sensitivity of the usage checks. Elevation Data Alternatives You might think that Google's elevation api is a bit of a nuisance what with the registering and sensitivity. Which it is. So why on earth are we using it? That's because it works reasonably predictably, offers effectively 100% coverage and is easy to use. The alternatives fail on most or all of these criteria. I could probably write something much more user friendly with no registration and zero cost. The problem is that would be a significant project of itself. Downloading, translating, securing and providing a convenient UI to provide elevation data would take substantial effort. The necessary hosting would probably also necessitate passing charges on to you the user. The GrayScale Elevation Tab This uses contours or an imported picture to work out elevations. The contours are those you draw ( covered above ). A picture can be any jpg or png picture which will be converted to 255 shades of grey internally. Although inadvisable, you could theoretically use a colour picture. Whichever picture you choose will be stretched to 1155 x 805 px. For most predictable ad precise results it is therefore advisable to use a greyscale picture which is 1155 x 805. The Elevation Shapers Tab The Menu The File Menu Load Background Open Map Save Map Exit Select this to exit the Map Editor program. The Preferences Menu Styling The Layers Menu Background This option toggles displaying the Background Image on / off. Elevation Map Terrain Places This option toggles displaying Placenames and Victory Points on/off. Grid This option toggles displaying the grid on/off. Compass Rose This options toggles displaying the Compass Rose '''on/off. '''Terrain Visualizer Combine Terrain Split Terrain Ground Scale The Help Menu About the Typography Instructions Map Scale Custom Options Considerable thought and effort has gone into creating all these tools and options. The intention is to broadly cover the things most users will want. For obvious practical reasons, they cannot possibly cover all the options anyone could ever think of. In order to provide total flexibility there is a final option which is intended for the advanced enthusiast. This allows you to add another layer in a canvas and or over ride styling. Whilst this might sound great in theory there is a catch ( isn't there always ). This is low level development in extended Application Markup Language ( XAML ). How this works is you create a XAML file called a Resource Dictionary in: %localappdata%\GeneralStaff\BlackPowder\Maps This must be named CustomResources.xaml. The content will be loaded dynamically when you run the map editor and merged into it's resources. If there is a Canvas with an x:Key="CustomCanvas" then this will be added as an extra layer on top of everything. You can add many things to a canvas but most likely are shapes such as Rectangle, Ellipse or Path. To define what they are you use the Tag property of these. These are matched against a specific list of terrain. They must match exactly. List of Terrains: Empty Water Swamp BUA Woods Bridge Road Fort Field Mud Fence Hedge Wall Notes: BUA = Built Up Area = buildings / city Fort = Fortifications such as breastworks as well as an actual fort. Example File You can download an example file from: https://drive.google.com/file/d/1bbbNsBW7lXjSpq371D1Tbgw47atGVxUj/view?usp=sharing This adds a starfort shaped Path which has a Tag="Fort" How To If you're not a WPF developer then you will want to stick to simple stuff first. XAML is rather like HTML so you will immediately see there's xml format opening and closing tags. It is very easy to make mistakes so you will need some sort of tooling to test what you're doing immediately. You could install Vistual Studio community ( free ) but this is quite a big install. There are various XAML pad options which are far quicker lighter installs - such as XampPadX https://blogs.msdn.microsoft.com/llobo/2008/08/25/xamlpadx-4-0/ Note that the Windows store XAML Pad is aimed at a different version of XAML than WPF and therefore not a good option. In order to test my markup in XamlPadX it needs a bit of adaptation. When you start up the app it gives you a Page to host your markup. Add a resources section to that and paste your resource dictionary markup into that. Then reference the canvas using a StaticResource. This is probably way clearer when seen than described. You should have something like: The "Geometry" is used to define a series of X,Y co-ordinates which tell it where the path is to be drawn and filled. I didn't create all these manually. InkScape There's a free piece of software called InkScape which is great for manipulating and creating vectors like our app uses. https://inkscape.org/en/ If you find a picture you want to turn into a piece of terrain you can use InkScape's automatic conversion to get the data for a Geometry. Open the bmp/jpg in InkScape and choose Path > Trace BitMap. There are a load of options but you can either choose colour and multiple layers = multiple geometries. Or you can choose black and white. The Star Fort was done using black and white. Once done click Simplify. You will now have two layers, one is the original picture and the other your new vector representation. Drag the vector off to one side and delete your original. Drag the vector back to the top left corner. Choose Save As > XAML ( checking the Silverlight option is usually best ). You then have a text file with a .xaml extension. If you edit in notepad there will be a load of stuff and one or more paths. These will have the characteristic long string of x,y co-ordinates. Cut and paste these into your own geometries in your own custom resource dictionary. This is a huge subject and video explanations are planned.